home *** CD-ROM | disk | FTP | other *** search
/ PC World 2006 July & August / PCWorld_2006-07-08_cd.bin / komunikace / apache / apache_2[1].2.2-win32-x86-no_ssl.msi / Data1.cab / _D0983A78DBFC348F0959B59FD114583A < prev    next >
Text File  |  2005-09-21  |  59KB  |  1,465 lines
  1. /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
  2.  * applicable.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  *     http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Unless required by applicable law or agreed to in writing, software
  11.  * distributed under the License is distributed on an "AS IS" BASIS,
  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13.  * See the License for the specific language governing permissions and
  14.  * limitations under the License.
  15.  */
  16. /**
  17.  * @file apr_buckets.h
  18.  * @brief APR-UTIL Buckets/Bucket Brigades
  19.  */
  20.  
  21. #ifndef APR_BUCKETS_H
  22. #define APR_BUCKETS_H
  23.  
  24. #if defined(APR_BUCKET_DEBUG) && !defined(APR_RING_DEBUG)
  25. #define APR_RING_DEBUG
  26. #endif
  27.  
  28. #include "apu.h"
  29. #include "apr_network_io.h"
  30. #include "apr_file_io.h"
  31. #include "apr_general.h"
  32. #include "apr_mmap.h"
  33. #include "apr_errno.h"
  34. #include "apr_ring.h"
  35. #include "apr.h"
  36. #if APR_HAVE_SYS_UIO_H
  37. #include <sys/uio.h>    /* for struct iovec */
  38. #endif
  39. #if APR_HAVE_STDARG_H
  40. #include <stdarg.h>
  41. #endif
  42.  
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46.  
  47. /**
  48.  * @defgroup APR_Util_Bucket_Brigades Bucket Brigades
  49.  * @ingroup APR_Util
  50.  * @{ 
  51.  */
  52.  
  53. /** default bucket buffer size - 8KB minus room for memory allocator headers */
  54. #define APR_BUCKET_BUFF_SIZE 8000
  55.  
  56. /** Determines how a bucket or brigade should be read */
  57. typedef enum {
  58.     APR_BLOCK_READ,   /**< block until data becomes available */
  59.     APR_NONBLOCK_READ /**< return immediately if no data is available */
  60. } apr_read_type_e;
  61.  
  62. /**
  63.  * The one-sentence buzzword-laden overview: Bucket brigades represent
  64.  * a complex data stream that can be passed through a layered IO
  65.  * system without unnecessary copying. A longer overview follows...
  66.  *
  67.  * A bucket brigade is a doubly linked list (ring) of buckets, so we
  68.  * aren't limited to inserting at the front and removing at the end.
  69.  * Buckets are only passed around as members of a brigade, although
  70.  * singleton buckets can occur for short periods of time.
  71.  *
  72.  * Buckets are data stores of various types. They can refer to data in
  73.  * memory, or part of a file or mmap area, or the output of a process,
  74.  * etc. Buckets also have some type-dependent accessor functions:
  75.  * read, split, copy, setaside, and destroy.
  76.  *
  77.  * read returns the address and size of the data in the bucket. If the
  78.  * data isn't in memory then it is read in and the bucket changes type
  79.  * so that it can refer to the new location of the data. If all the
  80.  * data doesn't fit in the bucket then a new bucket is inserted into
  81.  * the brigade to hold the rest of it.
  82.  *
  83.  * split divides the data in a bucket into two regions. After a split
  84.  * the original bucket refers to the first part of the data and a new
  85.  * bucket inserted into the brigade after the original bucket refers
  86.  * to the second part of the data. Reference counts are maintained as
  87.  * necessary.
  88.  *
  89.  * setaside ensures that the data in the bucket has a long enough
  90.  * lifetime. Sometimes it is convenient to create a bucket referring
  91.  * to data on the stack in the expectation that it will be consumed
  92.  * (output to the network) before the stack is unwound. If that
  93.  * expectation turns out not to be valid, the setaside function is
  94.  * called to move the data somewhere safer.
  95.  *
  96.  * copy makes a duplicate of the bucket structure as long as it's
  97.  * possible to have multiple references to a single copy of the
  98.  * data itself.  Not all bucket types can be copied.
  99.  *
  100.  * destroy maintains the reference counts on the resources used by a
  101.  * bucket and frees them if necessary.
  102.  *
  103.  * Note: all of the above functions have wrapper macros (apr_bucket_read(),
  104.  * apr_bucket_destroy(), etc), and those macros should be used rather
  105.  * than using the function pointers directly.
  106.  *
  107.  * To write a bucket brigade, they are first made into an iovec, so that we
  108.  * don't write too little data at one time.  Currently we ignore compacting the
  109.  * buckets into as few buckets as possible, but if we really want good
  110.  * performance, then we need to compact the buckets before we convert to an
  111.  * iovec, or possibly while we are converting to an iovec.
  112.  */
  113.  
  114. /*
  115.  * Forward declaration of the main types.
  116.  */
  117.  
  118. /** @see apr_bucket_brigade */
  119. typedef struct apr_bucket_brigade apr_bucket_brigade;
  120. /** @see apr_bucket */
  121. typedef struct apr_bucket apr_bucket;
  122. /** @see apr_bucket_alloc_t */
  123. typedef struct apr_bucket_alloc_t apr_bucket_alloc_t;
  124.  
  125. /** @see apr_bucket_type_t */
  126. typedef struct apr_bucket_type_t apr_bucket_type_t;
  127.  
  128. /**
  129.  * Basic bucket type
  130.  */
  131. struct apr_bucket_type_t {
  132.     /**
  133.      * The name of the bucket type
  134.      */
  135.     const char *name;
  136.     /** 
  137.      * The number of functions this bucket understands.  Can not be less than
  138.      * five.
  139.      */
  140.     int num_func;
  141.     /**
  142.      * Whether the bucket contains metadata (ie, information that
  143.      * describes the regular contents of the brigade).  The metadata
  144.      * is not returned by apr_bucket_read() and is not indicated by
  145.      * the ->length of the apr_bucket itself.  In other words, an
  146.      * empty bucket is safe to arbitrarily remove if and only if it
  147.      * contains no metadata.  In this sense, "data" is just raw bytes
  148.      * that are the "content" of the brigade and "metadata" describes
  149.      * that data but is not a proper part of it.
  150.      */
  151.     enum {
  152.         /** This bucket type represents actual data to send to the client. */
  153.         APR_BUCKET_DATA = 0,
  154.         /** This bucket type represents metadata. */
  155.         APR_BUCKET_METADATA = 1
  156.     } is_metadata;
  157.     /**
  158.      * Free the private data and any resources used by the bucket (if they
  159.      *  aren't shared with another bucket).  This function is required to be
  160.      *  implemented for all bucket types, though it might be a no-op on some
  161.      *  of them (namely ones that never allocate any private data structures).
  162.      * @param data The private data pointer from the bucket to be destroyed
  163.      */
  164.     void (*destroy)(void *data);
  165.  
  166.     /**
  167.      * Read the data from the bucket. This is required to be implemented
  168.      *  for all bucket types.
  169.      * @param b The bucket to read from
  170.      * @param str A place to store the data read.  Allocation should only be
  171.      *            done if absolutely necessary. 
  172.      * @param len The amount of data read.
  173.      * @param block Should this read function block if there is more data that
  174.      *              cannot be read immediately.
  175.      */
  176.     apr_status_t (*read)(apr_bucket *b, const char **str, apr_size_t *len, 
  177.                          apr_read_type_e block);
  178.     
  179.     /**
  180.      * Make it possible to set aside the data for at least as long as the
  181.      *  given pool. Buckets containing data that could potentially die before
  182.      *  this pool (e.g. the data resides on the stack, in a child pool of
  183.      *  the given pool, or in a disjoint pool) must somehow copy, shift, or
  184.      *  transform the data to have the proper lifetime.
  185.      * @param e The bucket to convert
  186.      * @remark Some bucket types contain data that will always outlive the
  187.      *         bucket itself. For example no data (EOS and FLUSH), or the data
  188.      *         resides in global, constant memory (IMMORTAL), or the data is on
  189.      *      the heap (HEAP). For these buckets, apr_bucket_setaside_noop can
  190.      *      be used.
  191.      */
  192.     apr_status_t (*setaside)(apr_bucket *e, apr_pool_t *pool);
  193.  
  194.     /**
  195.      * Split one bucket in two at the specified position by duplicating
  196.      *  the bucket structure (not the data) and modifying any necessary
  197.      *  start/end/offset information.  If it's not possible to do this
  198.      *  for the bucket type (perhaps the length of the data is indeterminate,
  199.      *  as with pipe and socket buckets), then APR_ENOTIMPL is returned.
  200.      * @param e The bucket to split
  201.      * @param point The offset of the first byte in the new bucket
  202.      */
  203.     apr_status_t (*split)(apr_bucket *e, apr_size_t point);
  204.  
  205.     /**
  206.      * Copy the bucket structure (not the data), assuming that this is
  207.      *  possible for the bucket type. If it's not, APR_ENOTIMPL is returned.
  208.      * @param e The bucket to copy
  209.      * @param c Returns a pointer to the new bucket
  210.      */
  211.     apr_status_t (*copy)(apr_bucket *e, apr_bucket **c);
  212.  
  213. };
  214.  
  215. /**
  216.  * apr_bucket structures are allocated on the malloc() heap and
  217.  * their lifetime is controlled by the parent apr_bucket_brigade
  218.  * structure. Buckets can move from one brigade to another e.g. by
  219.  * calling APR_BRIGADE_CONCAT(). In general the data in a bucket has
  220.  * the same lifetime as the bucket and is freed when the bucket is
  221.  * destroyed; if the data is shared by more than one bucket (e.g.
  222.  * after a split) the data is freed when the last bucket goes away.
  223.  */
  224. struct apr_bucket {
  225.     /** Links to the rest of the brigade */
  226.     APR_RING_ENTRY(apr_bucket) link;
  227.     /** The type of bucket.  */
  228.     const apr_bucket_type_t *type;
  229.     /** The length of the data in the bucket.  This could have been implemented
  230.      *  with a function, but this is an optimization, because the most
  231.      *  common thing to do will be to get the length.  If the length is unknown,
  232.      *  the value of this field will be (apr_size_t)(-1).
  233.      */
  234.     apr_size_t length;
  235.     /** The start of the data in the bucket relative to the private base
  236.      *  pointer.  The vast majority of bucket types allow a fixed block of
  237.      *  data to be referenced by multiple buckets, each bucket pointing to
  238.      *  a different segment of the data.  That segment starts at base+start
  239.      *  and ends at base+start+length.  
  240.      *  If the length == (apr_size_t)(-1), then start == -1.
  241.      */
  242.     apr_off_t start;
  243.     /** type-dependent data hangs off this pointer */
  244.     void *data;    
  245.     /**
  246.      * Pointer to function used to free the bucket. This function should
  247.      * always be defined and it should be consistent with the memory
  248.      * function used to allocate the bucket. For example, if malloc() is 
  249.      * used to allocate the bucket, this pointer should point to free().
  250.      * @param e Pointer to the bucket being freed
  251.      */
  252.     void (*free)(void *e);
  253.     /** The freelist from which this bucket was allocated */
  254.     apr_bucket_alloc_t *list;
  255. };
  256.  
  257. /** A list of buckets */
  258. struct apr_bucket_brigade {
  259.     /** The pool to associate the brigade with.  The data is not allocated out
  260.      *  of the pool, but a cleanup is registered with this pool.  If the 
  261.      *  brigade is destroyed by some mechanism other than pool destruction,
  262.      *  the destroying function is responsible for killing the cleanup.
  263.      */
  264.     apr_pool_t *p;
  265.     /** The buckets in the brigade are on this list. */
  266.     /*
  267.      * The apr_bucket_list structure doesn't actually need a name tag
  268.      * because it has no existence independent of struct apr_bucket_brigade;
  269.      * the ring macros are designed so that you can leave the name tag
  270.      * argument empty in this situation but apparently the Windows compiler
  271.      * doesn't like that.
  272.      */
  273.     APR_RING_HEAD(apr_bucket_list, apr_bucket) list;
  274.     /** The freelist from which this bucket was allocated */
  275.     apr_bucket_alloc_t *bucket_alloc;
  276. };
  277.  
  278.  
  279. /**
  280.  * Function called when a brigade should be flushed
  281.  */
  282. typedef apr_status_t (*apr_brigade_flush)(apr_bucket_brigade *bb, void *ctx);
  283.  
  284. /*
  285.  * define APR_BUCKET_DEBUG if you want your brigades to be checked for
  286.  * validity at every possible instant.  this will slow your code down
  287.  * substantially but is a very useful debugging tool.
  288.  */
  289. #ifdef APR_BUCKET_DEBUG
  290.  
  291. #define APR_BRIGADE_CHECK_CONSISTENCY(b)                \
  292.         APR_RING_CHECK_CONSISTENCY(&(b)->list, apr_bucket, link)
  293.  
  294. #define APR_BUCKET_CHECK_CONSISTENCY(e)                    \
  295.         APR_RING_CHECK_ELEM_CONSISTENCY((e), apr_bucket, link)
  296.  
  297. #else
  298. /**
  299.  * checks the ring pointers in a bucket brigade for consistency.  an
  300.  * abort() will be triggered if any inconsistencies are found.
  301.  *   note: this is a no-op unless APR_BUCKET_DEBUG is defined.
  302.  * @param b The brigade
  303.  */
  304. #define APR_BRIGADE_CHECK_CONSISTENCY(b)
  305. /**
  306.  * checks the brigade a bucket is in for ring consistency.  an
  307.  * abort() will be triggered if any inconsistencies are found.
  308.  *   note: this is a no-op unless APR_BUCKET_DEBUG is defined.
  309.  * @param e The bucket
  310.  */
  311. #define APR_BUCKET_CHECK_CONSISTENCY(e)
  312. #endif
  313.  
  314.  
  315. /**
  316.  * Wrappers around the RING macros to reduce the verbosity of the code
  317.  * that handles bucket brigades.
  318.  */
  319. /**
  320.  * The magic pointer value that indicates the head of the brigade
  321.  * @remark This is used to find the beginning and end of the brigade, eg:
  322.  * <pre>
  323.  *      while (e != APR_BRIGADE_SENTINEL(b)) {
  324.  *          ...
  325.  *          e = APR_BUCKET_NEXT(e);
  326.  *      }
  327.  * </pre>
  328.  * @param  b The brigade
  329.  * @return The magic pointer value
  330.  */
  331. #define APR_BRIGADE_SENTINEL(b)    APR_RING_SENTINEL(&(b)->list, apr_bucket, link)
  332.  
  333. /**
  334.  * Determine if the bucket brigade is empty
  335.  * @param b The brigade to check
  336.  * @return true or false
  337.  */
  338. #define APR_BRIGADE_EMPTY(b)    APR_RING_EMPTY(&(b)->list, apr_bucket, link)
  339.  
  340. /**
  341.  * Return the first bucket in a brigade
  342.  * @param b The brigade to query
  343.  * @return The first bucket in the brigade
  344.  */
  345. #define APR_BRIGADE_FIRST(b)    APR_RING_FIRST(&(b)->list)
  346. /**
  347.  * Return the last bucket in a brigade
  348.  * @param b The brigade to query
  349.  * @return The last bucket in the brigade
  350.  */
  351. #define APR_BRIGADE_LAST(b)    APR_RING_LAST(&(b)->list)
  352.  
  353. /**
  354.  * Insert a list of buckets at the front of a brigade
  355.  * @param b The brigade to add to
  356.  * @param e The first bucket in a list of buckets to insert
  357.  */
  358. #define APR_BRIGADE_INSERT_HEAD(b, e) do {                \
  359.     apr_bucket *ap__b = (e);                                        \
  360.     APR_RING_INSERT_HEAD(&(b)->list, ap__b, apr_bucket, link);    \
  361.         APR_BRIGADE_CHECK_CONSISTENCY((b));                \
  362.     } while (0)
  363.  
  364. /**
  365.  * Insert a list of buckets at the end of a brigade
  366.  * @param b The brigade to add to
  367.  * @param e The first bucket in a list of buckets to insert
  368.  */
  369. #define APR_BRIGADE_INSERT_TAIL(b, e) do {                \
  370.     apr_bucket *ap__b = (e);                    \
  371.     APR_RING_INSERT_TAIL(&(b)->list, ap__b, apr_bucket, link);    \
  372.         APR_BRIGADE_CHECK_CONSISTENCY((b));                \
  373.     } while (0)
  374.  
  375. /**
  376.  * Concatenate brigade b onto the end of brigade a, leaving brigade b empty
  377.  * @param a The first brigade
  378.  * @param b The second brigade
  379.  */
  380. #define APR_BRIGADE_CONCAT(a, b) do {                    \
  381.         APR_RING_CONCAT(&(a)->list, &(b)->list, apr_bucket, link);    \
  382.         APR_BRIGADE_CHECK_CONSISTENCY((a));                \
  383.     } while (0)
  384.  
  385. /**
  386.  * Prepend brigade b onto the beginning of brigade a, leaving brigade b empty
  387.  * @param a The first brigade
  388.  * @param b The second brigade
  389.  */
  390. #define APR_BRIGADE_PREPEND(a, b) do {                    \
  391.         APR_RING_PREPEND(&(a)->list, &(b)->list, apr_bucket, link);    \
  392.         APR_BRIGADE_CHECK_CONSISTENCY((a));                \
  393.     } while (0)
  394.  
  395. /**
  396.  * Insert a list of buckets before a specified bucket
  397.  * @param a The bucket to insert before
  398.  * @param b The buckets to insert
  399.  */
  400. #define APR_BUCKET_INSERT_BEFORE(a, b) do {                \
  401.     apr_bucket *ap__a = (a), *ap__b = (b);                \
  402.     APR_RING_INSERT_BEFORE(ap__a, ap__b, link);            \
  403.         APR_BUCKET_CHECK_CONSISTENCY(ap__a);                \
  404.     } while (0)
  405.  
  406. /**
  407.  * Insert a list of buckets after a specified bucket
  408.  * @param a The bucket to insert after
  409.  * @param b The buckets to insert
  410.  */
  411. #define APR_BUCKET_INSERT_AFTER(a, b) do {                \
  412.     apr_bucket *ap__a = (a), *ap__b = (b);                \
  413.     APR_RING_INSERT_AFTER(ap__a, ap__b, link);            \
  414.         APR_BUCKET_CHECK_CONSISTENCY(ap__a);                \
  415.     } while (0)
  416.  
  417. /**
  418.  * Get the next bucket in the list
  419.  * @param e The current bucket
  420.  * @return The next bucket
  421.  */
  422. #define APR_BUCKET_NEXT(e)    APR_RING_NEXT((e), link)
  423. /**
  424.  * Get the previous bucket in the list
  425.  * @param e The current bucket
  426.  * @return The previous bucket
  427.  */
  428. #define APR_BUCKET_PREV(e)    APR_RING_PREV((e), link)
  429.  
  430. /**
  431.  * Remove a bucket from its bucket brigade
  432.  * @param e The bucket to remove
  433.  */
  434. #define APR_BUCKET_REMOVE(e)    APR_RING_REMOVE((e), link)
  435.  
  436. /**
  437.  * Initialize a new bucket's prev/next pointers
  438.  * @param e The bucket to initialize
  439.  */
  440. #define APR_BUCKET_INIT(e)    APR_RING_ELEM_INIT((e), link)
  441.  
  442. /**
  443.  * Determine if a bucket contains metadata.  An empty bucket is
  444.  * safe to arbitrarily remove if and only if this is false.
  445.  * @param e The bucket to inspect
  446.  * @return true or false
  447.  */
  448. #define APR_BUCKET_IS_METADATA(e)    ((e)->type->is_metadata)
  449.  
  450. /**
  451.  * Determine if a bucket is a FLUSH bucket
  452.  * @param e The bucket to inspect
  453.  * @return true or false
  454.  */
  455. #define APR_BUCKET_IS_FLUSH(e)       ((e)->type == &apr_bucket_type_flush)
  456. /**
  457.  * Determine if a bucket is an EOS bucket
  458.  * @param e The bucket to inspect
  459.  * @return true or false
  460.  */
  461. #define APR_BUCKET_IS_EOS(e)         ((e)->type == &apr_bucket_type_eos)
  462. /**
  463.  * Determine if a bucket is a FILE bucket
  464.  * @param e The bucket to inspect
  465.  * @return true or false
  466.  */
  467. #define APR_BUCKET_IS_FILE(e)        ((e)->type == &apr_bucket_type_file)
  468. /**
  469.  * Determine if a bucket is a PIPE bucket
  470.  * @param e The bucket to inspect
  471.  * @return true or false
  472.  */
  473. #define APR_BUCKET_IS_PIPE(e)        ((e)->type == &apr_bucket_type_pipe)
  474. /**
  475.  * Determine if a bucket is a SOCKET bucket
  476.  * @param e The bucket to inspect
  477.  * @return true or false
  478.  */
  479. #define APR_BUCKET_IS_SOCKET(e)      ((e)->type == &apr_bucket_type_socket)
  480. /**
  481.  * Determine if a bucket is a HEAP bucket
  482.  * @param e The bucket to inspect
  483.  * @return true or false
  484.  */
  485. #define APR_BUCKET_IS_HEAP(e)        ((e)->type == &apr_bucket_type_heap)
  486. /**
  487.  * Determine if a bucket is a TRANSIENT bucket
  488.  * @param e The bucket to inspect
  489.  * @return true or false
  490.  */
  491. #define APR_BUCKET_IS_TRANSIENT(e)   ((e)->type == &apr_bucket_type_transient)
  492. /**
  493.  * Determine if a bucket is a IMMORTAL bucket
  494.  * @param e The bucket to inspect
  495.  * @return true or false
  496.  */
  497. #define APR_BUCKET_IS_IMMORTAL(e)    ((e)->type == &apr_bucket_type_immortal)
  498. #if APR_HAS_MMAP
  499. /**
  500.  * Determine if a bucket is a MMAP bucket
  501.  * @param e The bucket to inspect
  502.  * @return true or false
  503.  */
  504. #define APR_BUCKET_IS_MMAP(e)        ((e)->type == &apr_bucket_type_mmap)
  505. #endif
  506. /**
  507.  * Determine if a bucket is a POOL bucket
  508.  * @param e The bucket to inspect
  509.  * @return true or false
  510.  */
  511. #define APR_BUCKET_IS_POOL(e)        ((e)->type == &apr_bucket_type_pool)
  512.  
  513. /*
  514.  * General-purpose reference counting for the various bucket types.
  515.  *
  516.  * Any bucket type that keeps track of the resources it uses (i.e.
  517.  * most of them except for IMMORTAL, TRANSIENT, and EOS) needs to
  518.  * attach a reference count to the resource so that it can be freed
  519.  * when the last bucket that uses it goes away. Resource-sharing may
  520.  * occur because of bucket splits or buckets that refer to globally
  521.  * cached data. */
  522.  
  523. /** @see apr_bucket_refcount */
  524. typedef struct apr_bucket_refcount apr_bucket_refcount;
  525. /**
  526.  * The structure used to manage the shared resource must start with an
  527.  * apr_bucket_refcount which is updated by the general-purpose refcount
  528.  * code. A pointer to the bucket-type-dependent private data structure
  529.  * can be cast to a pointer to an apr_bucket_refcount and vice versa.
  530.  */
  531. struct apr_bucket_refcount {
  532.     /** The number of references to this bucket */
  533.     int          refcount;
  534. };
  535.  
  536. /*  *****  Reference-counted bucket types  *****  */
  537.  
  538. /** @see apr_bucket_heap */
  539. typedef struct apr_bucket_heap apr_bucket_heap;
  540. /**
  541.  * A bucket referring to data allocated off the heap.
  542.  */
  543. struct apr_bucket_heap {
  544.     /** Number of buckets using this memory */
  545.     apr_bucket_refcount  refcount;
  546.     /** The start of the data actually allocated.  This should never be
  547.      * modified, it is only used to free the bucket.
  548.      */
  549.     char    *base;
  550.     /** how much memory was allocated */
  551.     apr_size_t  alloc_len;
  552.     /** function to use to delete the data */
  553.     void (*free_func)(void *data);
  554. };
  555.  
  556. /** @see apr_bucket_pool */
  557. typedef struct apr_bucket_pool apr_bucket_pool;
  558. /**
  559.  * A bucket referring to data allocated from a pool
  560.  */
  561. struct apr_bucket_pool {
  562.     /** The pool bucket must be able to be easily morphed to a heap
  563.      * bucket if the pool gets cleaned up before all references are
  564.      * destroyed.  This apr_bucket_heap structure is populated automatically
  565.      * when the pool gets cleaned up, and subsequent calls to pool_read()
  566.      * will result in the apr_bucket in question being morphed into a
  567.      * regular heap bucket.  (To avoid having to do many extra refcount
  568.      * manipulations and b->data manipulations, the apr_bucket_pool
  569.      * struct actually *contains* the apr_bucket_heap struct that it
  570.      * will become as its first element; the two share their
  571.      * apr_bucket_refcount members.)
  572.      */
  573.     apr_bucket_heap  heap;
  574.     /** The block of data actually allocated from the pool.
  575.      * Segments of this block are referenced by adjusting
  576.      * the start and length of the apr_bucket accordingly.
  577.      * This will be NULL after the pool gets cleaned up.
  578.      */
  579.     const char *base;
  580.     /** The pool the data was allocated from.  When the pool
  581.      * is cleaned up, this gets set to NULL as an indicator
  582.      * to pool_read() that the data is now on the heap and
  583.      * so it should morph the bucket into a regular heap
  584.      * bucket before continuing.
  585.      */
  586.     apr_pool_t *pool;
  587.     /** The freelist this structure was allocated from, which is
  588.      * needed in the cleanup phase in order to allocate space on the heap
  589.      */
  590.     apr_bucket_alloc_t *list;
  591. };
  592.  
  593. #if APR_HAS_MMAP
  594. /** @see apr_bucket_mmap */
  595. typedef struct apr_bucket_mmap apr_bucket_mmap;
  596. /**
  597.  * A bucket referring to an mmap()ed file
  598.  */
  599. struct apr_bucket_mmap {
  600.     /** Number of buckets using this memory */
  601.     apr_bucket_refcount  refcount;
  602.     /** The mmap this sub_bucket refers to */
  603.     apr_mmap_t *mmap;
  604. };
  605. #endif
  606.  
  607. /** @see apr_bucket_file */
  608. typedef struct apr_bucket_file apr_bucket_file;
  609. /**
  610.  * A bucket referring to an file
  611.  */
  612. struct apr_bucket_file {
  613.     /** Number of buckets using this memory */
  614.     apr_bucket_refcount  refcount;
  615.     /** The file this bucket refers to */
  616.     apr_file_t *fd;
  617.     /** The pool into which any needed structures should
  618.      *  be created while reading from this file bucket */
  619.     apr_pool_t *readpool;
  620. #if APR_HAS_MMAP
  621.     /** Whether this bucket should be memory-mapped if
  622.      *  a caller tries to read from it */
  623.     int can_mmap;
  624. #endif /* APR_HAS_MMAP */
  625. };
  626.  
  627. /** @see apr_bucket_structs */
  628. typedef union apr_bucket_structs apr_bucket_structs;
  629. /**
  630.  * A union of all bucket structures so we know what
  631.  * the max size is.
  632.  */
  633. union apr_bucket_structs {
  634.     apr_bucket      b;      /**< Bucket */
  635.     apr_bucket_heap heap;   /**< Heap */
  636.     apr_bucket_pool pool;   /**< Pool */
  637. #if APR_HAS_MMAP
  638.     apr_bucket_mmap mmap;   /**< MMap */
  639. #endif
  640.     apr_bucket_file file;   /**< File */
  641. };
  642.  
  643. /**
  644.  * The amount that apr_bucket_alloc() should allocate in the common case.
  645.  * Note: this is twice as big as apr_bucket_structs to allow breathing
  646.  * room for third-party bucket types.
  647.  */
  648. #define APR_BUCKET_ALLOC_SIZE  APR_ALIGN_DEFAULT(2*sizeof(apr_bucket_structs))
  649.  
  650. /*  *****  Bucket Brigade Functions  *****  */
  651. /**
  652.  * Create a new bucket brigade.  The bucket brigade is originally empty.
  653.  * @param p The pool to associate with the brigade.  Data is not allocated out
  654.  *          of the pool, but a cleanup is registered.
  655.  * @param list The bucket allocator to use
  656.  * @return The empty bucket brigade
  657.  */
  658. APU_DECLARE(apr_bucket_brigade *) apr_brigade_create(apr_pool_t *p,
  659.                                                      apr_bucket_alloc_t *list);
  660.  
  661. /**
  662.  * destroy an entire bucket brigade.  This includes destroying all of the
  663.  * buckets within the bucket brigade's bucket list. 
  664.  * @param b The bucket brigade to destroy
  665.  */
  666. APU_DECLARE(apr_status_t) apr_brigade_destroy(apr_bucket_brigade *b);
  667.  
  668. /**
  669.  * empty out an entire bucket brigade.  This includes destroying all of the
  670.  * buckets within the bucket brigade's bucket list.  This is similar to
  671.  * apr_brigade_destroy(), except that it does not deregister the brigade's
  672.  * pool cleanup function.
  673.  * @param data The bucket brigade to clean up
  674.  * @remark Generally, you should use apr_brigade_destroy().  This function
  675.  *         can be useful in situations where you have a single brigade that
  676.  *         you wish to reuse many times by destroying all of the buckets in
  677.  *         the brigade and putting new buckets into it later.
  678.  */
  679. APU_DECLARE(apr_status_t) apr_brigade_cleanup(void *data);
  680.  
  681. /**
  682.  * Split a bucket brigade into two, such that the given bucket is the
  683.  * first in the new bucket brigade. This function is useful when a
  684.  * filter wants to pass only the initial part of a brigade to the next
  685.  * filter.
  686.  * @param b The brigade to split
  687.  * @param e The first element of the new brigade
  688.  * @return The new brigade
  689.  */
  690. APU_DECLARE(apr_bucket_brigade *) apr_brigade_split(apr_bucket_brigade *b,
  691.                                                     apr_bucket *e);
  692.  
  693. /**
  694.  * Partition a bucket brigade at a given offset (in bytes from the start of
  695.  * the brigade).  This is useful whenever a filter wants to use known ranges
  696.  * of bytes from the brigade; the ranges can even overlap.
  697.  * @param b The brigade to partition
  698.  * @param point The offset at which to partition the brigade
  699.  * @param after_point Returns a pointer to the first bucket after the partition
  700.  * @return APR_SUCCESS on success, APR_INCOMPLETE if the contents of the
  701.  * brigade were shorter than @a point, or an error code.
  702.  * @remark if APR_INCOMPLETE is returned, @a after_point will be set to
  703.  * the brigade sentinel.
  704.  */
  705. APU_DECLARE(apr_status_t) apr_brigade_partition(apr_bucket_brigade *b,
  706.                                                 apr_off_t point,
  707.                                                 apr_bucket **after_point);
  708.  
  709. /**
  710.  * Return the total length of the brigade.
  711.  * @param bb The brigade to compute the length of
  712.  * @param read_all Read unknown-length buckets to force a size
  713.  * @param length Returns the length of the brigade, or -1 if the brigade has
  714.  *               buckets of indeterminate length and read_all is 0.
  715.  */
  716. APU_DECLARE(apr_status_t) apr_brigade_length(apr_bucket_brigade *bb,
  717.                                              int read_all,
  718.                                              apr_off_t *length);
  719.  
  720. /**
  721.  * Take a bucket brigade and store the data in a flat char*
  722.  * @param bb The bucket brigade to create the char* from
  723.  * @param c The char* to write into
  724.  * @param len The maximum length of the char array. On return, it is the
  725.  *            actual length of the char array.
  726.  */
  727. APU_DECLARE(apr_status_t) apr_brigade_flatten(apr_bucket_brigade *bb,
  728.                                               char *c,
  729.                                               apr_size_t *len);
  730.  
  731. /**
  732.  * Creates a pool-allocated string representing a flat bucket brigade
  733.  * @param bb The bucket brigade to create the char array from
  734.  * @param c On return, the allocated char array
  735.  * @param len On return, the length of the char array.
  736.  * @param pool The pool to allocate the string from.
  737.  */
  738. APU_DECLARE(apr_status_t) apr_brigade_pflatten(apr_bucket_brigade *bb, 
  739.                                                char **c,
  740.                                                apr_size_t *len,
  741.                                                apr_pool_t *pool);
  742.  
  743. /**
  744.  * Split a brigade to represent one LF line.
  745.  * @param bbOut The bucket brigade that will have the LF line appended to.
  746.  * @param bbIn The input bucket brigade to search for a LF-line.
  747.  * @param block The blocking mode to be used to split the line.
  748.  * @param maxbytes The maximum bytes to read.  If this many bytes are seen
  749.  *                 without a LF, the brigade will contain a partial line.
  750.  */
  751. APU_DECLARE(apr_status_t) apr_brigade_split_line(apr_bucket_brigade *bbOut,
  752.                                                  apr_bucket_brigade *bbIn,
  753.                                                  apr_read_type_e block,
  754.                                                  apr_off_t maxbytes);
  755.  
  756. /**
  757.  * create an iovec of the elements in a bucket_brigade... return number 
  758.  * of elements used.  This is useful for writing to a file or to the
  759.  * network efficiently.
  760.  * @param b The bucket brigade to create the iovec from
  761.  * @param vec The iovec to create
  762.  * @param nvec The number of elements in the iovec. On return, it is the
  763.  *             number of iovec elements actually filled out.
  764.  */
  765. APU_DECLARE(apr_status_t) apr_brigade_to_iovec(apr_bucket_brigade *b, 
  766.                                                struct iovec *vec, int *nvec);
  767.  
  768. /**
  769.  * This function writes a list of strings into a bucket brigade. 
  770.  * @param b The bucket brigade to add to
  771.  * @param flush The flush function to use if the brigade is full
  772.  * @param ctx The structure to pass to the flush function
  773.  * @param va A list of strings to add
  774.  * @return APR_SUCCESS or error code.
  775.  */
  776. APU_DECLARE(apr_status_t) apr_brigade_vputstrs(apr_bucket_brigade *b,
  777.                                                apr_brigade_flush flush,
  778.                                                void *ctx,
  779.                                                va_list va);
  780.  
  781. /**
  782.  * This function writes a string into a bucket brigade.
  783.  * @param b The bucket brigade to add to
  784.  * @param flush The flush function to use if the brigade is full
  785.  * @param ctx The structure to pass to the flush function
  786.  * @param str The string to add
  787.  * @param nbyte The number of bytes to write
  788.  * @return APR_SUCCESS or error code
  789.  */
  790. APU_DECLARE(apr_status_t) apr_brigade_write(apr_bucket_brigade *b,
  791.                                             apr_brigade_flush flush, void *ctx,
  792.                                             const char *str, apr_size_t nbyte);
  793.  
  794. /**
  795.  * This function writes multiple strings into a bucket brigade.
  796.  * @param b The bucket brigade to add to
  797.  * @param flush The flush function to use if the brigade is full
  798.  * @param ctx The structure to pass to the flush function
  799.  * @param vec The strings to add (address plus length for each)
  800.  * @param nvec The number of entries in iovec
  801.  * @return APR_SUCCESS or error code
  802.  */
  803. APU_DECLARE(apr_status_t) apr_brigade_writev(apr_bucket_brigade *b,
  804.                                              apr_brigade_flush flush,
  805.                                              void *ctx,
  806.                                              const struct iovec *vec,
  807.                                              apr_size_t nvec);
  808.  
  809. /**
  810.  * This function writes a string into a bucket brigade.
  811.  * @param bb The bucket brigade to add to
  812.  * @param flush The flush function to use if the brigade is full
  813.  * @param ctx The structure to pass to the flush function
  814.  * @param str The string to add
  815.  * @return APR_SUCCESS or error code
  816.  */
  817. APU_DECLARE(apr_status_t) apr_brigade_puts(apr_bucket_brigade *bb,
  818.                                            apr_brigade_flush flush, void *ctx,
  819.                                            const char *str);
  820.  
  821. /**
  822.  * This function writes a character into a bucket brigade.
  823.  * @param b The bucket brigade to add to
  824.  * @param flush The flush function to use if the brigade is full
  825.  * @param ctx The structure to pass to the flush function
  826.  * @param c The character to add
  827.  * @return APR_SUCCESS or error code
  828.  */
  829. APU_DECLARE(apr_status_t) apr_brigade_putc(apr_bucket_brigade *b,
  830.                                            apr_brigade_flush flush, void *ctx,
  831.                                            const char c);
  832.  
  833. /**
  834.  * This function writes an unspecified number of strings into a bucket brigade.
  835.  * @param b The bucket brigade to add to
  836.  * @param flush The flush function to use if the brigade is full
  837.  * @param ctx The structure to pass to the flush function
  838.  * @param ... The strings to add
  839.  * @return APR_SUCCESS or error code
  840.  */
  841. APU_DECLARE_NONSTD(apr_status_t) apr_brigade_putstrs(apr_bucket_brigade *b,
  842.                                                      apr_brigade_flush flush,
  843.                                                      void *ctx, ...);
  844.  
  845. /**
  846.  * Evaluate a printf and put the resulting string at the end 
  847.  * of the bucket brigade.
  848.  * @param b The brigade to write to
  849.  * @param flush The flush function to use if the brigade is full
  850.  * @param ctx The structure to pass to the flush function
  851.  * @param fmt The format of the string to write
  852.  * @param ... The arguments to fill out the format
  853.  * @return APR_SUCCESS or error code
  854.  */
  855. APU_DECLARE_NONSTD(apr_status_t) apr_brigade_printf(apr_bucket_brigade *b, 
  856.                                                     apr_brigade_flush flush,
  857.                                                     void *ctx,
  858.                                                     const char *fmt, ...)
  859.         __attribute__((format(printf,4,5)));
  860.  
  861. /**
  862.  * Evaluate a printf and put the resulting string at the end 
  863.  * of the bucket brigade.
  864.  * @param b The brigade to write to
  865.  * @param flush The flush function to use if the brigade is full
  866.  * @param ctx The structure to pass to the flush function
  867.  * @param fmt The format of the string to write
  868.  * @param va The arguments to fill out the format
  869.  * @return APR_SUCCESS or error code
  870.  */
  871. APU_DECLARE(apr_status_t) apr_brigade_vprintf(apr_bucket_brigade *b, 
  872.                                               apr_brigade_flush flush,
  873.                                               void *ctx,
  874.                                               const char *fmt, va_list va);
  875.  
  876. /**
  877.  * Utility function to insert a file (or a segment of a file) onto the
  878.  * end of the brigade.  The file is split into multiple buckets if it
  879.  * is larger than the maximum size which can be represented by a
  880.  * single bucket.
  881.  * @param bb the brigade to insert into
  882.  * @param f the file to insert
  883.  * @param start the offset of the start of the segment
  884.  * @param len the length of the segment of the file to insert
  885.  * @param p pool from which file buckets are allocated
  886.  * @return the last bucket inserted
  887.  */
  888. APU_DECLARE(apr_bucket *) apr_brigade_insert_file(apr_bucket_brigade *bb,
  889.                                                   apr_file_t *f,
  890.                                                   apr_off_t start,
  891.                                                   apr_off_t len,
  892.                                                   apr_pool_t *p);
  893.  
  894.  
  895.  
  896. /*  *****  Bucket freelist functions *****  */
  897. /**
  898.  * Create a bucket allocator.
  899.  * @param p This pool's underlying apr_allocator_t is used to allocate memory
  900.  *          for the bucket allocator.  When the pool is destroyed, the bucket
  901.  *          allocator's cleanup routine will free all memory that has been
  902.  *          allocated from it.
  903.  * @remark  The reason the allocator gets its memory from the pool's
  904.  *          apr_allocator_t rather than from the pool itself is because
  905.  *          the bucket allocator will free large memory blocks back to the
  906.  *          allocator when it's done with them, thereby preventing memory
  907.  *          footprint growth that would occur if we allocated from the pool.
  908.  * @warning The allocator must never be used by more than one thread at a time.
  909.  */
  910. APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create(apr_pool_t *p);
  911.  
  912. /**
  913.  * Create a bucket allocator.
  914.  * @param allocator This apr_allocator_t is used to allocate both the bucket
  915.  *          allocator and all memory handed out by the bucket allocator.  The
  916.  *          caller is responsible for destroying the bucket allocator and the
  917.  *          apr_allocator_t -- no automatic cleanups will happen.
  918.  * @warning The allocator must never be used by more than one thread at a time.
  919.  */
  920. APU_DECLARE_NONSTD(apr_bucket_alloc_t *) apr_bucket_alloc_create_ex(apr_allocator_t *allocator);
  921.  
  922. /**
  923.  * Destroy a bucket allocator.
  924.  * @param list The allocator to be destroyed
  925.  */
  926. APU_DECLARE_NONSTD(void) apr_bucket_alloc_destroy(apr_bucket_alloc_t *list);
  927.  
  928. /**
  929.  * Allocate memory for use by the buckets.
  930.  * @param size The amount to allocate.
  931.  * @param list The allocator from which to allocate the memory.
  932.  */
  933. APU_DECLARE_NONSTD(void *) apr_bucket_alloc(apr_size_t size, apr_bucket_alloc_t *list);
  934.  
  935. /**
  936.  * Free memory previously allocated with apr_bucket_alloc().
  937.  * @param block The block of memory to be freed.
  938.  */
  939. APU_DECLARE_NONSTD(void) apr_bucket_free(void *block);
  940.  
  941.  
  942. /*  *****  Bucket Functions  *****  */
  943. /**
  944.  * Free the resources used by a bucket. If multiple buckets refer to
  945.  * the same resource it is freed when the last one goes away.
  946.  * @see apr_bucket_delete()
  947.  * @param e The bucket to destroy
  948.  */
  949. #define apr_bucket_destroy(e) do {                    \
  950.         (e)->type->destroy((e)->data);                    \
  951.         (e)->free(e);                            \
  952.     } while (0)
  953.  
  954. /**
  955.  * Delete a bucket by removing it from its brigade (if any) and then
  956.  * destroying it.
  957.  * @remark This mainly acts as an aid in avoiding code verbosity.  It is
  958.  * the preferred exact equivalent to:
  959.  * <pre>
  960.  *      APR_BUCKET_REMOVE(e);
  961.  *      apr_bucket_destroy(e);
  962.  * </pre>
  963.  * @param e The bucket to delete
  964.  */
  965. #define apr_bucket_delete(e) do {                    \
  966.         APR_BUCKET_REMOVE(e);                        \
  967.         apr_bucket_destroy(e);                        \
  968.     } while (0)
  969.  
  970. /**
  971.  * read the data from the bucket
  972.  * @param e The bucket to read from
  973.  * @param str The location to store the data in
  974.  * @param len The amount of data read
  975.  * @param block Whether the read function blocks
  976.  */
  977. #define apr_bucket_read(e,str,len,block) (e)->type->read(e, str, len, block)
  978.  
  979. /**
  980.  * Setaside data so that stack data is not destroyed on returning from
  981.  * the function
  982.  * @param e The bucket to setaside
  983.  * @param p The pool to setaside into
  984.  */
  985. #define apr_bucket_setaside(e,p) (e)->type->setaside(e,p)
  986.  
  987. /**
  988.  * Split one bucket in two.
  989.  * @param e The bucket to split
  990.  * @param point The offset to split the bucket at
  991.  */
  992. #define apr_bucket_split(e,point) (e)->type->split(e, point)
  993.  
  994. /**
  995.  * Copy a bucket.
  996.  * @param e The bucket to copy
  997.  * @param c Returns a pointer to the new bucket
  998.  */
  999. #define apr_bucket_copy(e,c) (e)->type->copy(e, c)
  1000.  
  1001. /* Bucket type handling */
  1002.  
  1003. /**
  1004.  * This function simply returns APR_SUCCESS to denote that the bucket does
  1005.  * not require anything to happen for its setaside() function. This is
  1006.  * appropriate for buckets that have "immortal" data -- the data will live
  1007.  * at least as long as the bucket.
  1008.  * @param data The bucket to setaside
  1009.  * @param pool The pool defining the desired lifetime of the bucket data
  1010.  * @return APR_SUCCESS
  1011.  */ 
  1012. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_noop(apr_bucket *data,
  1013.                                                           apr_pool_t *pool);
  1014.  
  1015. /**
  1016.  * A place holder function that signifies that the setaside function was not
  1017.  * implemented for this bucket
  1018.  * @param data The bucket to setaside
  1019.  * @param pool The pool defining the desired lifetime of the bucket data
  1020.  * @return APR_ENOTIMPL
  1021.  */ 
  1022. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_setaside_notimpl(apr_bucket *data,
  1023.                                                              apr_pool_t *pool);
  1024.  
  1025. /**
  1026.  * A place holder function that signifies that the split function was not
  1027.  * implemented for this bucket
  1028.  * @param data The bucket to split
  1029.  * @param point The location to split the bucket
  1030.  * @return APR_ENOTIMPL
  1031.  */ 
  1032. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_split_notimpl(apr_bucket *data,
  1033.                                                           apr_size_t point);
  1034.  
  1035. /**
  1036.  * A place holder function that signifies that the copy function was not
  1037.  * implemented for this bucket
  1038.  * @param e The bucket to copy
  1039.  * @param c Returns a pointer to the new bucket
  1040.  * @return APR_ENOTIMPL
  1041.  */
  1042. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_copy_notimpl(apr_bucket *e,
  1043.                                                          apr_bucket **c);
  1044.  
  1045. /**
  1046.  * A place holder function that signifies that this bucket does not need
  1047.  * to do anything special to be destroyed.  That's only the case for buckets
  1048.  * that either have no data (metadata buckets) or buckets whose data pointer
  1049.  * points to something that's not a bucket-type-specific structure, as with
  1050.  * simple buckets where data points to a string and pipe buckets where data
  1051.  * points directly to the apr_file_t.
  1052.  * @param data The bucket data to destroy
  1053.  */ 
  1054. APU_DECLARE_NONSTD(void) apr_bucket_destroy_noop(void *data);
  1055.  
  1056. /**
  1057.  * There is no apr_bucket_destroy_notimpl, because destruction is required
  1058.  * to be implemented (it could be a noop, but only if that makes sense for
  1059.  * the bucket type)
  1060.  */
  1061.  
  1062. /* There is no apr_bucket_read_notimpl, because it is a required function
  1063.  */
  1064.  
  1065.  
  1066. /* All of the bucket types implemented by the core */
  1067. /**
  1068.  * The flush bucket type.  This signifies that all data should be flushed to
  1069.  * the next filter.  The flush bucket should be sent with the other buckets.
  1070.  */
  1071. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_flush;
  1072. /**
  1073.  * The EOS bucket type.  This signifies that there will be no more data, ever.
  1074.  * All filters MUST send all data to the next filter when they receive a
  1075.  * bucket of this type
  1076.  */
  1077. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_eos;
  1078. /**
  1079.  * The FILE bucket type.  This bucket represents a file on disk
  1080.  */
  1081. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_file;
  1082. /**
  1083.  * The HEAP bucket type.  This bucket represents a data allocated from the
  1084.  * heap.
  1085.  */
  1086. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_heap;
  1087. #if APR_HAS_MMAP
  1088. /**
  1089.  * The MMAP bucket type.  This bucket represents an MMAP'ed file
  1090.  */
  1091. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_mmap;
  1092. #endif
  1093. /**
  1094.  * The POOL bucket type.  This bucket represents a data that was allocated
  1095.  * from a pool.  IF this bucket is still available when the pool is cleared,
  1096.  * the data is copied on to the heap.
  1097.  */
  1098. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pool;
  1099. /**
  1100.  * The PIPE bucket type.  This bucket represents a pipe to another program.
  1101.  */
  1102. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_pipe;
  1103. /**
  1104.  * The IMMORTAL bucket type.  This bucket represents a segment of data that
  1105.  * the creator is willing to take responsibility for.  The core will do
  1106.  * nothing with the data in an immortal bucket
  1107.  */
  1108. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_immortal;
  1109. /**
  1110.  * The TRANSIENT bucket type.  This bucket represents a data allocated off
  1111.  * the stack.  When the setaside function is called, this data is copied on
  1112.  * to the heap
  1113.  */
  1114. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_transient;
  1115. /**
  1116.  * The SOCKET bucket type.  This bucket represents a socket to another machine
  1117.  */
  1118. APU_DECLARE_DATA extern const apr_bucket_type_t apr_bucket_type_socket;
  1119.  
  1120.  
  1121. /*  *****  Simple buckets  *****  */
  1122.  
  1123. /**
  1124.  * Split a simple bucket into two at the given point.  Most non-reference
  1125.  * counting buckets that allow multiple references to the same block of
  1126.  * data (eg transient and immortal) will use this as their split function
  1127.  * without any additional type-specific handling.
  1128.  * @param b The bucket to be split
  1129.  * @param point The offset of the first byte in the new bucket
  1130.  * @return APR_EINVAL if the point is not within the bucket;
  1131.  *         APR_ENOMEM if allocation failed;
  1132.  *         or APR_SUCCESS
  1133.  */
  1134. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_split(apr_bucket *b,
  1135.                                                          apr_size_t point);
  1136.  
  1137. /**
  1138.  * Copy a simple bucket.  Most non-reference-counting buckets that allow
  1139.  * multiple references to the same block of data (eg transient and immortal)
  1140.  * will use this as their copy function without any additional type-specific
  1141.  * handling.
  1142.  * @param a The bucket to copy
  1143.  * @param b Returns a pointer to the new bucket
  1144.  * @return APR_ENOMEM if allocation failed;
  1145.  *         or APR_SUCCESS
  1146.  */
  1147. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_simple_copy(apr_bucket *a,
  1148.                                                         apr_bucket **b);
  1149.  
  1150.  
  1151. /*  *****  Shared, reference-counted buckets  *****  */
  1152.  
  1153. /**
  1154.  * Initialize a bucket containing reference-counted data that may be
  1155.  * shared. The caller must allocate the bucket if necessary and
  1156.  * initialize its type-dependent fields, and allocate and initialize
  1157.  * its own private data structure. This function should only be called
  1158.  * by type-specific bucket creation functions.
  1159.  * @param b The bucket to initialize
  1160.  * @param data A pointer to the private data structure
  1161.  *             with the reference count at the start
  1162.  * @param start The start of the data in the bucket
  1163.  *              relative to the private base pointer
  1164.  * @param length The length of the data in the bucket
  1165.  * @return The new bucket, or NULL if allocation failed
  1166.  */
  1167. APU_DECLARE(apr_bucket *) apr_bucket_shared_make(apr_bucket *b, void *data,
  1168.                                  apr_off_t start, 
  1169.                                                  apr_size_t length);
  1170.  
  1171. /**
  1172.  * Decrement the refcount of the data in the bucket. This function
  1173.  * should only be called by type-specific bucket destruction functions.
  1174.  * @param data The private data pointer from the bucket to be destroyed
  1175.  * @return TRUE or FALSE; TRUE if the reference count is now
  1176.  *         zero, indicating that the shared resource itself can
  1177.  *         be destroyed by the caller.
  1178.  */
  1179. APU_DECLARE(int) apr_bucket_shared_destroy(void *data);
  1180.  
  1181. /**
  1182.  * Split a bucket into two at the given point, and adjust the refcount
  1183.  * to the underlying data. Most reference-counting bucket types will
  1184.  * be able to use this function as their split function without any
  1185.  * additional type-specific handling.
  1186.  * @param b The bucket to be split
  1187.  * @param point The offset of the first byte in the new bucket
  1188.  * @return APR_EINVAL if the point is not within the bucket;
  1189.  *         APR_ENOMEM if allocation failed;
  1190.  *         or APR_SUCCESS
  1191.  */
  1192. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_split(apr_bucket *b,
  1193.                                                          apr_size_t point);
  1194.  
  1195. /**
  1196.  * Copy a refcounted bucket, incrementing the reference count. Most
  1197.  * reference-counting bucket types will be able to use this function
  1198.  * as their copy function without any additional type-specific handling.
  1199.  * @param a The bucket to copy
  1200.  * @param b Returns a pointer to the new bucket
  1201.  * @return APR_ENOMEM if allocation failed;
  1202.            or APR_SUCCESS
  1203.  */
  1204. APU_DECLARE_NONSTD(apr_status_t) apr_bucket_shared_copy(apr_bucket *a,
  1205.                                                         apr_bucket **b);
  1206.  
  1207.  
  1208. /*  *****  Functions to Create Buckets of varying types  *****  */
  1209. /*
  1210.  * Each bucket type foo has two initialization functions:
  1211.  * apr_bucket_foo_make which sets up some already-allocated memory as a
  1212.  * bucket of type foo; and apr_bucket_foo_create which allocates memory
  1213.  * for the bucket, calls apr_bucket_make_foo, and initializes the
  1214.  * bucket's list pointers. The apr_bucket_foo_make functions are used
  1215.  * inside the bucket code to change the type of buckets in place;
  1216.  * other code should call apr_bucket_foo_create. All the initialization
  1217.  * functions change nothing if they fail.
  1218.  */
  1219.  
  1220. /**
  1221.  * Create an End of Stream bucket.  This indicates that there is no more data
  1222.  * coming from down the filter stack.  All filters should flush at this point.
  1223.  * @param list The freelist from which this bucket should be allocated
  1224.  * @return The new bucket, or NULL if allocation failed
  1225.  */
  1226. APU_DECLARE(apr_bucket *) apr_bucket_eos_create(apr_bucket_alloc_t *list);
  1227.  
  1228. /**
  1229.  * Make the bucket passed in an EOS bucket.  This indicates that there is no 
  1230.  * more data coming from down the filter stack.  All filters should flush at 
  1231.  * this point.
  1232.  * @param b The bucket to make into an EOS bucket
  1233.  * @return The new bucket, or NULL if allocation failed
  1234.  */
  1235. APU_DECLARE(apr_bucket *) apr_bucket_eos_make(apr_bucket *b);
  1236.  
  1237. /**
  1238.  * Create a flush  bucket.  This indicates that filters should flush their
  1239.  * data.  There is no guarantee that they will flush it, but this is the
  1240.  * best we can do.
  1241.  * @param list The freelist from which this bucket should be allocated
  1242.  * @return The new bucket, or NULL if allocation failed
  1243.  */
  1244. APU_DECLARE(apr_bucket *) apr_bucket_flush_create(apr_bucket_alloc_t *list);
  1245.  
  1246. /**
  1247.  * Make the bucket passed in a FLUSH  bucket.  This indicates that filters 
  1248.  * should flush their data.  There is no guarantee that they will flush it, 
  1249.  * but this is the best we can do.
  1250.  * @param b The bucket to make into a FLUSH bucket
  1251.  * @return The new bucket, or NULL if allocation failed
  1252.  */
  1253. APU_DECLARE(apr_bucket *) apr_bucket_flush_make(apr_bucket *b);
  1254.  
  1255. /**
  1256.  * Create a bucket referring to long-lived data.
  1257.  * @param buf The data to insert into the bucket
  1258.  * @param nbyte The size of the data to insert.
  1259.  * @param list The freelist from which this bucket should be allocated
  1260.  * @return The new bucket, or NULL if allocation failed
  1261.  */
  1262. APU_DECLARE(apr_bucket *) apr_bucket_immortal_create(const char *buf, 
  1263.                                                      apr_size_t nbyte,
  1264.                                                      apr_bucket_alloc_t *list);
  1265.  
  1266. /**
  1267.  * Make the bucket passed in a bucket refer to long-lived data
  1268.  * @param b The bucket to make into a IMMORTAL bucket
  1269.  * @param buf The data to insert into the bucket
  1270.  * @param nbyte The size of the data to insert.
  1271.  * @return The new bucket, or NULL if allocation failed
  1272.  */
  1273. APU_DECLARE(apr_bucket *) apr_bucket_immortal_make(apr_bucket *b, 
  1274.                                                    const char *buf, 
  1275.                                                    apr_size_t nbyte);
  1276.  
  1277. /**
  1278.  * Create a bucket referring to data on the stack.
  1279.  * @param buf The data to insert into the bucket
  1280.  * @param nbyte The size of the data to insert.
  1281.  * @param list The freelist from which this bucket should be allocated
  1282.  * @return The new bucket, or NULL if allocation failed
  1283.  */
  1284. APU_DECLARE(apr_bucket *) apr_bucket_transient_create(const char *buf, 
  1285.                                                       apr_size_t nbyte,
  1286.                                                       apr_bucket_alloc_t *list);
  1287.  
  1288. /**
  1289.  * Make the bucket passed in a bucket refer to stack data
  1290.  * @param b The bucket to make into a TRANSIENT bucket
  1291.  * @param buf The data to insert into the bucket
  1292.  * @param nbyte The size of the data to insert.
  1293.  * @return The new bucket, or NULL if allocation failed
  1294.  */
  1295. APU_DECLARE(apr_bucket *) apr_bucket_transient_make(apr_bucket *b, 
  1296.                                                     const char *buf,
  1297.                                                     apr_size_t nbyte);
  1298.  
  1299. /**
  1300.  * Create a bucket referring to memory on the heap. If the caller asks
  1301.  * for the data to be copied, this function always allocates 4K of
  1302.  * memory so that more data can be added to the bucket without
  1303.  * requiring another allocation. Therefore not all the data may be put
  1304.  * into the bucket. If copying is not requested then the bucket takes
  1305.  * over responsibility for free()ing the memory.
  1306.  * @param buf The buffer to insert into the bucket
  1307.  * @param nbyte The size of the buffer to insert.
  1308.  * @param free_func Function to use to free the data; NULL indicates that the
  1309.  *                  bucket should make a copy of the data
  1310.  * @param list The freelist from which this bucket should be allocated
  1311.  * @return The new bucket, or NULL if allocation failed
  1312.  */
  1313. APU_DECLARE(apr_bucket *) apr_bucket_heap_create(const char *buf, 
  1314.                                                  apr_size_t nbyte,
  1315.                                                  void (*free_func)(void *data),
  1316.                                                  apr_bucket_alloc_t *list);
  1317. /**
  1318.  * Make the bucket passed in a bucket refer to heap data
  1319.  * @param b The bucket to make into a HEAP bucket
  1320.  * @param buf The buffer to insert into the bucket
  1321.  * @param nbyte The size of the buffer to insert.
  1322.  * @param free_func Function to use to free the data; NULL indicates that the
  1323.  *                  bucket should make a copy of the data
  1324.  * @return The new bucket, or NULL if allocation failed
  1325.  */
  1326. APU_DECLARE(apr_bucket *) apr_bucket_heap_make(apr_bucket *b, const char *buf,
  1327.                                                apr_size_t nbyte,
  1328.                                                void (*free_func)(void *data));
  1329.  
  1330. /**
  1331.  * Create a bucket referring to memory allocated from a pool.
  1332.  *
  1333.  * @param buf The buffer to insert into the bucket
  1334.  * @param length The number of bytes referred to by this bucket
  1335.  * @param pool The pool the memory was allocated from
  1336.  * @param list The freelist from which this bucket should be allocated
  1337.  * @return The new bucket, or NULL if allocation failed
  1338.  */
  1339. APU_DECLARE(apr_bucket *) apr_bucket_pool_create(const char *buf, 
  1340.                                                  apr_size_t length,
  1341.                                                  apr_pool_t *pool,
  1342.                                                  apr_bucket_alloc_t *list);
  1343.  
  1344. /**
  1345.  * Make the bucket passed in a bucket refer to pool data
  1346.  * @param b The bucket to make into a pool bucket
  1347.  * @param buf The buffer to insert into the bucket
  1348.  * @param length The number of bytes referred to by this bucket
  1349.  * @param pool The pool the memory was allocated from
  1350.  * @return The new bucket, or NULL if allocation failed
  1351.  */
  1352. APU_DECLARE(apr_bucket *) apr_bucket_pool_make(apr_bucket *b, const char *buf,
  1353.                                                apr_size_t length, 
  1354.                                                apr_pool_t *pool);
  1355.  
  1356. #if APR_HAS_MMAP
  1357. /**
  1358.  * Create a bucket referring to mmap()ed memory.
  1359.  * @param mm The mmap to insert into the bucket
  1360.  * @param start The offset of the first byte in the mmap
  1361.  *              that this bucket refers to
  1362.  * @param length The number of bytes referred to by this bucket
  1363.  * @param list The freelist from which this bucket should be allocated
  1364.  * @return The new bucket, or NULL if allocation failed
  1365.  */
  1366. APU_DECLARE(apr_bucket *) apr_bucket_mmap_create(apr_mmap_t *mm, 
  1367.                                                  apr_off_t start,
  1368.                                                  apr_size_t length,
  1369.                                                  apr_bucket_alloc_t *list);
  1370.  
  1371. /**
  1372.  * Make the bucket passed in a bucket refer to an MMAP'ed file
  1373.  * @param b The bucket to make into a MMAP bucket
  1374.  * @param mm The mmap to insert into the bucket
  1375.  * @param start The offset of the first byte in the mmap
  1376.  *              that this bucket refers to
  1377.  * @param length The number of bytes referred to by this bucket
  1378.  * @return The new bucket, or NULL if allocation failed
  1379.  */
  1380. APU_DECLARE(apr_bucket *) apr_bucket_mmap_make(apr_bucket *b, apr_mmap_t *mm,
  1381.                                                apr_off_t start, 
  1382.                                                apr_size_t length);
  1383. #endif
  1384.  
  1385. /**
  1386.  * Create a bucket referring to a socket.
  1387.  * @param thissock The socket to put in the bucket
  1388.  * @param list The freelist from which this bucket should be allocated
  1389.  * @return The new bucket, or NULL if allocation failed
  1390.  */
  1391. APU_DECLARE(apr_bucket *) apr_bucket_socket_create(apr_socket_t *thissock,
  1392.                                                    apr_bucket_alloc_t *list);
  1393. /**
  1394.  * Make the bucket passed in a bucket refer to a socket
  1395.  * @param b The bucket to make into a SOCKET bucket
  1396.  * @param thissock The socket to put in the bucket
  1397.  * @return The new bucket, or NULL if allocation failed
  1398.  */
  1399. APU_DECLARE(apr_bucket *) apr_bucket_socket_make(apr_bucket *b, 
  1400.                                                  apr_socket_t *thissock);
  1401.  
  1402. /**
  1403.  * Create a bucket referring to a pipe.
  1404.  * @param thispipe The pipe to put in the bucket
  1405.  * @param list The freelist from which this bucket should be allocated
  1406.  * @return The new bucket, or NULL if allocation failed
  1407.  */
  1408. APU_DECLARE(apr_bucket *) apr_bucket_pipe_create(apr_file_t *thispipe,
  1409.                                                  apr_bucket_alloc_t *list);
  1410.  
  1411. /**
  1412.  * Make the bucket passed in a bucket refer to a pipe
  1413.  * @param b The bucket to make into a PIPE bucket
  1414.  * @param thispipe The pipe to put in the bucket
  1415.  * @return The new bucket, or NULL if allocation failed
  1416.  */
  1417. APU_DECLARE(apr_bucket *) apr_bucket_pipe_make(apr_bucket *b, 
  1418.                                                apr_file_t *thispipe);
  1419.  
  1420. /**
  1421.  * Create a bucket referring to a file.
  1422.  * @param fd The file to put in the bucket
  1423.  * @param offset The offset where the data of interest begins in the file
  1424.  * @param len The amount of data in the file we are interested in
  1425.  * @param p The pool into which any needed structures should be created
  1426.  *          while reading from this file bucket
  1427.  * @param list The freelist from which this bucket should be allocated
  1428.  * @return The new bucket, or NULL if allocation failed
  1429.  */
  1430. APU_DECLARE(apr_bucket *) apr_bucket_file_create(apr_file_t *fd,
  1431.                                                  apr_off_t offset,
  1432.                                                  apr_size_t len, 
  1433.                                                  apr_pool_t *p,
  1434.                                                  apr_bucket_alloc_t *list);
  1435.  
  1436. /**
  1437.  * Make the bucket passed in a bucket refer to a file
  1438.  * @param b The bucket to make into a FILE bucket
  1439.  * @param fd The file to put in the bucket
  1440.  * @param offset The offset where the data of interest begins in the file
  1441.  * @param len The amount of data in the file we are interested in
  1442.  * @param p The pool into which any needed structures should be created
  1443.  *          while reading from this file bucket
  1444.  * @return The new bucket, or NULL if allocation failed
  1445.  */
  1446. APU_DECLARE(apr_bucket *) apr_bucket_file_make(apr_bucket *b, apr_file_t *fd,
  1447.                                                apr_off_t offset,
  1448.                                                apr_size_t len, apr_pool_t *p);
  1449.  
  1450. /**
  1451.  * Enable or disable memory-mapping for a FILE bucket (default is enabled)
  1452.  * @param b The bucket
  1453.  * @param enabled Whether memory-mapping should be enabled
  1454.  * @return APR_SUCCESS normally, or an error code if the operation fails
  1455.  */
  1456. APU_DECLARE(apr_status_t) apr_bucket_file_enable_mmap(apr_bucket *b,
  1457.                                                       int enabled);
  1458.  
  1459. /** @} */
  1460. #ifdef __cplusplus
  1461. }
  1462. #endif
  1463.  
  1464. #endif /* !APR_BUCKETS_H */
  1465.